Getting started with GitLab CI/CD

Note: Starting from version 8.0, GitLab Continuous Integration (CI) is fully integrated into GitLab itself and is enables by default on all projects.

GitLab offers a continuous integration service. Add a .gitlab-ci.yml file to the root directory of the repository, and configure GitLab project to use a Runner, then each commit or push, triggers CI pipeline.

(補圖)

The .gitlab-ci.yml file tells the GitLab runner what to do. By default it runs a pipeline with three stages: build, test, and deploy. No need to use all three stages. Stages with no jobs are simply ignored.

If everything runs OK (no non-zero return values), we'll get a nice green checkmark associated with the commit. It's easy to see the fail of tests caused by a commit, we can check it before look at the code.

Sum up the steps needed to have a working CI:

Add .gitlab-ci.yml to the root directory of the repository
Configure a Runner

From there on, on every push to the Git repository, the runner will automatically start the pipeline, and the pipeline will appear under the project's Pipelines page.

This guide assumes that you:

have a working GitLab instance of version 8.0+r or are using GitLab.com
have a project in GitLab that we would like to use CI for

Creating a `.gitlab-ci.yml` file

Before creating .gitlab-ci.yml, first explain what this is all about.

What is `.gitlab-ci.yml`

The .gitlab-ci.yml file is a configuration, what CI does with the project. It lives in the root of the repository.

On any push to the repository, GitLab will look for the .gitlab-ci.yml file and start jobs on Runners according to the contents of the file, for that commit.

Because .gitlab-ci.yml is in the repository and is version controlled, if old versions still build successfully, forks can easily make use of CI, branches can have different pipelines and jobs, and have a single source of truth for CI.

Creating a simple `.gitlab-ci.yml` file

Note: .gitlab-ci.yml is a YAML file, so we have to pay extra attention to indentation. Always use spaces, not tabs.

Create a file named .gitlab-ci.yml int the root directory of the repository. Below is an example for a Ruby on Rails project.

before_script:
  - apt-get update -qq && apt-get install -y -qq sqlite3 libsqlite3-dev nodejs
  - ruby -v
  - which ruby
  - gem install bundler --no-ri --no-rdoc
  - bundle install --jobs $(nproc) "${FLAGS[@]}"

rspec:
  script:
    - bundle exec rspec

rubocop:
  script:
    - bundle exec rubocop

This is the simplest possible configuration that will work for most Ruby applications:

Define two jobs rspec and rubocop (the names are arbitrary) with different commands to be executed.
Before every job, the commands defined by before_script are executed.

The .gitlab-ci.yml file defines sets of jobs, and constraints of how and when the jobs should be run. The jobs are defined as top-level elements with a name (in the case rspec and rubocop ) and always have to contain the script keyword. Jobs are used to create jobs, which are then picked by Runners and executed within the environment of the Runner.

Each job is run independently from each other.

In order to check .gitlab-ci.yml file is valid, there is a Lint tool under the page /ci/lint of our GitLab instance. Can also find a "CI Lint" button to go to /ci/lint page under CI/CD -> Pipelines and Pipelines -> Jobs in the project.

For more information and a complete .gitlab-ci.yml syntax, please read the reference documentation on .gitlab-ci.yml.

Push .gitlab-ci.yml to GitLab

Once created .gitlab-ci.yml, add it to the Git repository and push it to GitLab.

git add .gitlab-ci.yml
git commit -m "Add .gitlab-ci.yml"
git push origin master

Now in the Pipelines page, the pipeline is pending.

In the Commits page, the little pause icon is next to the commit SHA.

Clicking on it will be directed to the jobs page for that specific commit.

There is a pending job in "Status" after we write in .gitlab-ci.yml . "stuck" indicates that there is no Runner configured yet for this job.

The next step is to configure a Runner, it picks the pending jobs.

Configuring a Runner

In GitLab, Runners run the jobs that defined in .gitlab-ci.yml . A Runner can be a virtual machine, a VPS, a bare-metal machine, a docker container or even a cluster of containers. GitLab and the Runners communicate through an API, so the only requirement is that the Runner's machine has internet access.

A Runner can be specific to a certain project or serve multiple projects in GitLab. If it serves all projects it's called a Shared Runner .

Find more information about different Runners in the Runners documentation.

Going to Settings -> CI/CD , find whether any Runners are assigned to the project.

A functional Runner needed to follow two steps:

Follow the links above to set up our own Runner or use a Shared Runner as described in the next section.

Once the Runner has been set up, following Settings -> CI/CD to see the Runners page of the project.

Shared Runners

We can use Shared Runners provided by GitLab Inc if we use GitLab.com

Shared Runners are special virtual machines that run on GitLab's infrastructure and can build any project.

To enable the Shared Runners we have to go to our project's Settings -> CI/CD and click Enable shared runners .

Status of pipeline and jobs

After successfully configure the Runner, we should see the project status from pending to either running, success or failed when we commit changed.

In the Pipelines page in the project can view all pipelines.

Or view all jobs in Pipelines -> Jobs page.

We are able to see the log of that job by clicking on a job's status. We can diagnose why a job failed or acted differently than expected by the log of the job.

Getting started with GitLab CI/CD